<HTML><HEAD><TITLE>shelf_set(+ShelfHandle, +Index, ?Term)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>shelf_set(+ShelfHandle, +Index, ?Term)</H1>
Store a term in a shelf object
<DL>
<DT><EM>ShelfHandle</EM></DT>
<DD>A shelf handle or shelf name
</DD>
<DT><EM>Index</EM></DT>
<DD>An integer
</DD>
<DT><EM>Term</EM></DT>
<DD>An arbitrary term
</DD>
</DL>
<H2>Description</H2>
	This stores an arbitrary term in the Index'th slot of the
	shelf object denoted by ShelfHandle.  All other slots of the
	shelf remain untouched.  The setting will persist until it is
	replaced with a new setting, or until the shelf is destroyed. 
	In particular, the setting will survive backtracking across
	the call to shelf_set/3.
<P>
	The slots are numbered from 1 to the maximum which was determined
	during shelf creation (but note that ECLiPSe's struct-syntax can
	be used to give the slots symbolic names, see struct/1).
<P>
	Calling shelf_set/3 with an Index of 0 can be used to set all
	slots at once. In this case, Term must be a compound term whose
	functor corresponds to the one that was given during shelf creation.
	Every shelf slot is set from the corresponding term argument.
<P>
	Storing and retrieving terms from a shelf involves copying the
	term each time, similar to what happens in setval/getval and
	record/recorded.  In particular, if the term contains variables,
	they lose their identity and are replaced with fresh ones.
	Also, the different slots of a shelf are separate entities,
	in particular, they cannot share variables between each other.
<P>
	Note: If ShelfHandle is not a handle, then it must be an atom or a
	compound term, and the shelf is identified by this term's toplevel
	functor together with the context module.
    
<H3>Modes and Determinism</H3><UL>
<LI>shelf_set(+, +, ?) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>ShelfHandle is not instantiated
<DT><EM>(5) type error </EM>
<DD>Index is not instantiated
<DT><EM>(5) type error </EM>
<DD>ShelfHandle is not a shelf
<DT><EM>(5) type error </EM>
<DD>Index is not an integer
<DT><EM>(6) out of range </EM>
<DD>Index is negative or greater than the number of slots on the shelf
<DT><EM>(40) stale object handle </EM>
<DD>ShelfHandle refers to an already destroyed shelf
</DL>
<H2>Examples</H2>
<PRE>For examples see shelf_create/2,3.</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/shelf_create-2.html">shelf_create / 2</A>, <A HREF="../../kernel/storage/shelf_create-3.html">shelf_create / 3</A>, <A HREF="../../kernel/storage/shelf_get-3.html">shelf_get / 3</A>, <A HREF="../../kernel/storage/shelf_abolish-1.html">shelf_abolish / 1</A>, <A HREF="../../kernel/syntax/struct-1.html">struct / 1</A>
</BODY></HTML>
